
<!DOCTYPE HTML>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>WTForms Documentation</title>
    <link rel="stylesheet" href="_static/main.css" type="text/css">
    <link rel="stylesheet" href="_static/docstyles.css" type="text/css">
    <link rel="stylesheet" href="_static/print.css" type="text/css" media="print">
    <link rel="stylesheet" href="_static/pygments.css" type="text/css">
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:   '#',
        VERSION:    '1.0.4'
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/searchtools.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="contents" title="Global table of contents" href="contents.html">
    <link rel="index" title="Global index" href="genindex.html">
    <link rel="search" title="Search" href="search.html">
    <link rel="top" title="WTForms 1.0.4 documentation" href="index.html">
    <link rel="next" title="Solving Specific Problems" href="specific_problems.html">
    <link rel="prev" title="Extensions" href="ext.html">
    
  </head>
  <body>
    <div id="body">
      <div id="header">
        <h1 id="logo"><a href="index.html"
          title="back to the documentation overview"><img src="_static/wtforms.png" alt="WTForms" /></a></h1>
        <ul id="menu">
          <li><a href="http://wtforms.simplecodes.com/">Website</li>
          <li><a href="index.html">Documentation</a></li>
          <li><a href="#">FAQ</a></li>
          <li><a href="http://groups.google.com/group/wtforms/">Mailing List</a></li>
          <li><a href="http://bitbucket.org/simplecodes/wtforms/">Code</a></li>
        </ul>
      </div>
      <div id="content">
        <div id="toc">
          <h3>Table Of Contents</h3>
          <div class="inner"><ul>
<li><a class="reference internal" href="#">FAQ</a><ul>
<li><a class="reference internal" href="#why-does-wtforms-copy-django-forms">Why does WTForms copy Django Forms?</a></li>
<li><a class="reference internal" href="#does-wtforms-work-with-library-here">Does WTForms work with [library here]?</a></li>
<li><a class="reference internal" href="#does-wtforms-support-unicode">Does WTForms support unicode?</a></li>
<li><a class="reference internal" href="#what-versions-of-python-are-supported">What versions of Python are supported?</a></li>
<li><a class="reference internal" href="#how-can-i-contribute-to-wtforms">How can I contribute to WTForms?</a></li>
<li><a class="reference internal" href="#how-do-i-mark-in-a-template-when-a-field-is-required">How do I mark in a template when a field is required?</a></li>
<li><a class="reference internal" href="#does-wtforms-handle-file-uploads">Does WTForms handle file uploads?</a></li>
<li><a class="reference internal" href="#why-does-blank-input-not-go-back-to-the-default-value">Why does blank input not go back to the default value?</a></li>
<li><a class="reference internal" href="#how-do-i-convoluted-combination-of-libraries">How do I... [convoluted combination of libraries]</a></li>
</ul>
</li>
</ul>
</div>
        </div>
        
  <div class="section" id="faq">
<h1>FAQ<a class="headerlink" href="#faq" title="Permalink to this headline">¶</a></h1>
<p>This contains the most commonly asked questions about WTForms. The most current
version of this document can always be found on the <a class="reference external" href="http://wtforms.simplecodes.com">WTForms Website</a>.</p>
<div class="section" id="why-does-wtforms-copy-django-forms">
<h2>Why does WTForms copy Django Forms?<a class="headerlink" href="#why-does-wtforms-copy-django-forms" title="Permalink to this headline">¶</a></h2>
<p>Were we a bit more audacious, we&#8217;d probably say Django Forms copied us, but the
reality is that WTForms and Django&#8217;s &#8220;newforms&#8221; were actually written at about
the same time.</p>
<p>When WTForms was written, our primary goals were to provide HTML customization
through templates, easily customized validation and a simple, declarative
ORM-style API. At the time there was no newforms and the other alternatives
either didn&#8217;t support HTML generation, were very tightly coupled with a
single framework, or relied too heavily on an ORM.</p>
</div>
<div class="section" id="does-wtforms-work-with-library-here">
<h2>Does WTForms work with [library here]?<a class="headerlink" href="#does-wtforms-work-with-library-here" title="Permalink to this headline">¶</a></h2>
<p>The answer is most likely <strong>yes</strong>. WTForms tries to provide as usable an API as
possible. We&#8217;ve listed here some of the known libraries to work with WTForms,
but if it&#8217;s not listed, it doesn&#8217;t mean it won&#8217;t work.</p>
<ul>
<li><p class="first"><strong>Request/Form Input</strong></p>
<ul class="simple">
<li>Django</li>
<li>Webob (Includes Pylons, Google App Engine, Turbogears)</li>
<li>Werkzeug (Includes Flask, Tipfy)</li>
<li>any other cgi.FieldStorage-type multidict</li>
</ul>
</li>
<li><p class="first"><strong>Templating Engines</strong></p>
<ul class="simple">
<li>Jinja2</li>
<li>Mako</li>
<li>Django Templates (To get the full power of WTForms in your templates, you
will need to use the Django <a class="reference internal" href="ext.html#module-wtforms.ext.django" title="wtforms.ext.django"><tt class="xref py py-mod docutils literal"><span class="pre">extension</span></tt></a>.)</li>
<li>Genshi</li>
</ul>
</li>
<li><p class="first"><strong>Database Objects</strong></p>
<ul>
<li><p class="first">Pretty much any ORM or object-DB should work, as long as data objects allow
attribute access to their members.</p>
<p>Special support is there for SQLAlchemy, Google App Engine, and Django
collections via <a class="reference internal" href="ext.html#module-wtforms.ext" title="wtforms.ext"><tt class="xref py py-mod docutils literal"><span class="pre">extensions</span></tt></a>.</p>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="does-wtforms-support-unicode">
<h2>Does WTForms support unicode?<a class="headerlink" href="#does-wtforms-support-unicode" title="Permalink to this headline">¶</a></h2>
<p>Simple answer: Yes.</p>
<p>Longer answer: WTForms uses unicode strings throughout the source code, and
assumes that form input has already been coerced to unicode by your framework
(Most frameworks already do this.) WTForms fields render to unicode strings by
default, and therefore as long as your templating engine can work with that,
you should have no unicode issues.</p>
</div>
<div class="section" id="what-versions-of-python-are-supported">
<h2>What versions of Python are supported?<a class="headerlink" href="#what-versions-of-python-are-supported" title="Permalink to this headline">¶</a></h2>
<p>WTForms supports Python 2.6-2.7 and 3.2+ with a single codebase. Without 2to3 tool.</p>
</div>
<div class="section" id="how-can-i-contribute-to-wtforms">
<h2>How can I contribute to WTForms?<a class="headerlink" href="#how-can-i-contribute-to-wtforms" title="Permalink to this headline">¶</a></h2>
<p>WTForms is not that scary. Really. We try to keep it as succint and readable as
possible. If you feel like you have something to contribute to WTForms, let us
know on the <a class="reference external" href="http://groups.google.com/group/wtforms">mailing list</a>. For bugs and feature requests, you can file a
ticket on the <a class="reference external" href="http://bitbucket.org/simplecodes/wtforms">project page</a>.</p>
</div>
<div class="section" id="how-do-i-mark-in-a-template-when-a-field-is-required">
<h2>How do I mark in a template when a field is required?<a class="headerlink" href="#how-do-i-mark-in-a-template-when-a-field-is-required" title="Permalink to this headline">¶</a></h2>
<p>Some validators (notably Required and Optional) set flags on the fields&#8217;
<a class="reference internal" href="fields.html#wtforms.fields.Field.flags" title="wtforms.fields.Field.flags"><tt class="xref py py-attr docutils literal"><span class="pre">flags</span></tt></a> object. To use this in a template, you can
do something like:</p>
<div class="highlight-html+jinja"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">for</span> <span class="nv">field</span> <span class="k">in</span> <span class="nv">form</span> <span class="cp">%}</span>
    <span class="cp">{{</span> <span class="nv">field</span> <span class="cp">}}</span>
    <span class="cp">{%</span> <span class="k">if</span> <span class="nv">field.flags.required</span> <span class="cp">%}</span>*<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}{{</span> <span class="nv">field.label</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
</div>
<div class="section" id="does-wtforms-handle-file-uploads">
<h2>Does WTForms handle file uploads?<a class="headerlink" href="#does-wtforms-handle-file-uploads" title="Permalink to this headline">¶</a></h2>
<p>Currently, it does not. This is because WTForms strives to be
framework-agnostic, and every web framework handles file uploads somewhat
differently. WTForms has a <a class="reference internal" href="fields.html#wtforms.fields.FileField" title="wtforms.fields.FileField"><tt class="xref py py-class docutils literal"><span class="pre">FileField</span></tt></a> which will let
you render a file input widget, but the rest is up to you. An example use in a
django-ish framework:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyForm</span><span class="p">(</span><span class="n">Form</span><span class="p">):</span>
    <span class="n">image</span> <span class="o">=</span> <span class="n">FileField</span><span class="p">()</span>

<span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="n">form</span> <span class="o">=</span> <span class="n">MyForm</span><span class="p">(</span><span class="n">request</span><span class="o">.</span><span class="n">POST</span><span class="p">)</span>
    <span class="n">file_wrapper</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">FILES</span><span class="p">[</span><span class="n">form</span><span class="o">.</span><span class="n">image</span><span class="o">.</span><span class="n">name</span><span class="p">]</span>
    <span class="c"># Do things with your file wrapper now</span>
</pre></div>
</div>
<p>Using <tt class="docutils literal"><span class="pre">form.image.name</span></tt> is an easy way to know what input name was generated
for your file input, even if the form is prefixed.</p>
</div>
<div class="section" id="why-does-blank-input-not-go-back-to-the-default-value">
<h2>Why does blank input not go back to the default value?<a class="headerlink" href="#why-does-blank-input-not-go-back-to-the-default-value" title="Permalink to this headline">¶</a></h2>
<p>A key design decision of WTForms was that form data -always- takes precedence
when there&#8217;s a form submission. That is, if a field exists on a form, and a
form was posted, but that field&#8217;s value was missing, it will not revert to a
default, but instead store an empty value (and in some cases cause a validation
error.)</p>
<p>This is for a number of reasons:</p>
<ol class="arabic simple">
<li>Security. If a form reverted to defaults on missing data, then an evil user
could potentially cause problems by submitting a hand-coded form with key
missing fields.</li>
<li>Bug-finding. If you omitted a field in your template, it might fall through
to the default and you&#8217;d possibly miss it.</li>
<li>Consistency.</li>
</ol>
<dl class="docutils">
<dt>See the following mailing list posts for more discussion on the topic:</dt>
<dd><ul class="first last simple">
<li><a class="reference external" href="http://groups.google.com/group/wtforms/browse_frm/thread/6755a45a13878e9">http://groups.google.com/group/wtforms/browse_frm/thread/6755a45a13878e9</a></li>
<li><a class="reference external" href="http://groups.google.com/group/wtforms/msg/fa409c8c89b6f62d">http://groups.google.com/group/wtforms/msg/fa409c8c89b6f62d</a></li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="how-do-i-convoluted-combination-of-libraries">
<h2>How do I... [convoluted combination of libraries]<a class="headerlink" href="#how-do-i-convoluted-combination-of-libraries" title="Permalink to this headline">¶</a></h2>
<p>You&#8217;ll probably want to check out our
<a class="reference internal" href="specific_problems.html#specific-problems"><em>Solving Specific Problems</em></a> doc.</p>
</div>
</div>


        <div style="clear: both"></div>
      </div>
      <div id="footer">
        © Copyright 2010 by the <a href="http://wtforms.simplecodes.com">WTForms Team</a>,
        documentation generated by <a href="http://sphinx.pocoo.org/">Sphinx</a>
      </div>
    </div>
  </body>
</html>